2023/6/4 h% 9:18 EIP-5792: Wallet Function Call API 


EIP-5792: Wallet Function Call API O © 


Adds JSON-RPC methods for sending multiple 
function calls from the user's wallet, and checking 
their status 


Authors Moody Salem (@moodysalem) 
Created 2022-10-17 


Discussion Link https://ethereum-magicians.org/t/eip-5792-wallet-abstract- 
transaction-send-api/11374 


Table of Contents 


e Abstract 

e Motivation 

e Specification 
o wallet_sendFunctionCallBundle 
o wallet_getBundleStatus 
o wallet_showBundleStatus 

e Rationale 

e Backwards Compatibility 

e Security Considerations 

e Copyright 


Abstract 


Defines new JSON-RPC methods for dapps to send batches of function calls from a 
user's wallet, as well as check on the status of those calls. The new methods are more 
abstract in regard to the underlying transactions than the existing transaction 
sending APIs to allow for differences between wallet implementations, e.g. smart 
contract wallets utilizing EIP-4337 or EOA wallets that support bundled transactions 
via EIP-3074. Dapps may use this more abstract interface to support different kinds of 
wallets without additional effort, as well as provide a better UX for sending bundles 
of function calls (e.g. EIP-20 #approve followed by a contract call). 


Motivation 
The current methods used to send transactions from the user wallet and check their 


status are eth_sendTransaction and eth_getTransactionReceipt . 
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These methods are keyed on the hash of the on-chain transaction, i.e. 
eth_sendTransaction returns an transaction hash computed from the transaction 
parameters, and eth_getTransactionReceipt takes as one argument the transaction 
hash. When the transaction hash changes, for example when a user speeds up the 
transaction in their wallet, the transaction hash that the dapp is aware of becomes 
irrelevant. There is no communication delivered to the dapp of the change in 
transaction hash, and no way to connect the old transaction hash to the new one, 
except by the user account and transaction nonce. It is not trivial for the dapp to find 
all signed transactions for a given nonce and account, especially for smart contract 
accounts which usually store the nonce in a contract storage slot. This happens more 
frequently with smart contract wallets, which usually use a third party relaying service 
and automatically re-broadcast transactions with higher gas prices. 


These methods also do not support sending multiple function calls related to a single 
action. For example, when swapping on Uniswap, the user must often call EIP-20 
#approve before calling the Uniswap router contract to swap. The dapp has to 
manage a complex multi-step asynchronous workflow to guide the user through 
sending a single swap. The ideal UX would be to bundle the approve call with the 
swap call, and abstract the underlying approve function call from the user. 


The current interface also does not work well for account abstracted wallets (e.g. EIP- 
4337 or EIP-3074), which often involve a relaying service to sign and broadcast the 
transaction that triggers the function calls from the user's wallet. In these cases the 
actual transaction hash may not be known at the time of user signing, but must still 
be returned by eth_sendTransaction . The transaction hash returned by 
eth_sendTransaction in these cases is unlikely to be relevant to the transaction hash 
of the included transaction. The existing interface also provides no way to delay the 
resolution of the transaction hash, since it is used as the key of the transaction 
tracked by the dapp. Dapps often link to the block explorer for the returned 
transaction hash, but in these cases the transaction hash is wrong and the link will 
not work. 


Dapps need a better interface for sending batches of function calls from the user's 
wallet so they can interact with wallets without considering the differences between 
wallet implementations. These methods are backwards compatible with existing EOA 
wallets. EOA wallets may send bundles of function calls as individual transactions. The 
goal of the new interface is to be a more stable and flexible interface that enables a 
better user experience, while wallet implementations evolve over time. 


Specification 
Three new JSON-RPC methods are added. Dapps may begin using these methods 


immediately, falling back to eth_sendTransaction and eth_getTransactionReceipt 
when they are not available. 
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wallet_sendFunctionCallBundle 


Requests that the wallet deliver a group of function calls on-chain from the user's 
wallet. 


The wallet: 


e MUST send these calls in the order specified in the request. 

e MUST send the calls on the request chain ID. 

e MUST stop executing the calls if any call fails 

e MUST NOT send any calls from the request if the user rejects the request 

e MAY revert all calls if any call fails 

e MAY send all the function calls as part of one transaction or multiple 
transactions, depending on wallet capability. 

e MAY reject the request if the request chain ID does not match the currently 
selected chain ID. 

e MAY reject the request if the from address does not match the enabled 
account. 

e MAY reject the request if one or more calls in the bundle is expected to fail, 
when simulated sequentially 


wallet_sendFunctionCallBundle OpenRPC Specification 


- name: wallet_sendFunctionCallBundle 
summary: Sends a bundle of function calls from the user wallet 
params: 
- name: Function calls 
required: true 
schema: 
type: object 
title: Send function call bundle request 
required: 
- chainId 
- from 
- calls 
properties: 
chainId: 
title: chainId 
description: Chain ID that these calls should be sent on 
$ref: '#/components/schemas/uint' 
from: 
title: from address 
description: The address from which the function calls should be sent 
$ref: '#/components/schemas/address' 
calls: 
title: calls to make 
description: The calls that the wallet should make from the user's addre 
type: array 
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minItems: 1 
items: 
title: function call 
description: A single function call 
type: object 
required: 
- gas 
- data 
to: 
title: to address 
description: The address that is being called 
$ref: '#/components/schemas/address' 
gas: 
title: gas limit 
description: The gas limit for this particular call 
$ref: '#/components/schemas/uint' 
value: 
title: value 
description: How much value to send with the call 
$ref: '#/components/schemas/uint' 
data: 
title: data 
description: The data to send with the function call 
$ref: '#/components/schemas/bytes' 
result: 
name: Bundle identifier 
schema: 
type: string 
maxLength: 66 


wallet_sendFunctionCallBundle Example Parameters 


[ 
{ 
"chainId": 1, 
"from": "Əxd46e8dd67c5d32be8058bb8eb9708790f07244567", 
"calls": [ 
{ 


"to": "@xd46e8dd67c5d32be8058bb8eb970870f07244567", 

"gas": "0x76c0", 

"value": "0x9184e72a", 

"data": "@xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870F072445675058bb8e 


"to": "@xd46e8dd67c5d32be8058bb8eb970870f07244567", 
"gas": "@xdefa", 

"value": "0x182183", 

"data": "Oxfbadbafe1" 
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wallet_sendFunctionCallBundle Example Return Value 
The identifier may be the hash of the call bundle, e.g.: 


"@xe670eCc64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" 


The identifier may be a numeric identifier represented as a hex string, e.g.: 


"®xO@1 " 


The identifier may be a base64 encoded string: 


"aGVsbG8gd29ybGQ=" 


wallet_getBundleStatus > 


Returns the status of a bundle that was sent via wallet_sendFunctionCallBundle . The 
identifier of the bundle is the value returned from the wallet_sendFunctionCallBundle 
RPC. Note this method only returns a subset of fields that eth_getTransactionReceipt 
returns, excluding any fields that may differ across wallet implementations. 


wallet_getBundleStatus OpenRPC Specification 


- name: wallet_getBundleStatus 
summary: Sends a bundle of function calls from the user wallet 
params: 
- name: Bundle identifier 
required: true 
schema: 
type: string 
title: Bundle identifier 
result: 
name: Call status 
schema: 
type: object 
properties: 
calls: 
type: array 
items: 
title: call status 
description: Status of the call at the given index 
type: object 
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status: 
title: The current status of the call 
enum: 
- CONFIRMED 
- PENDING 
receipt: 
type: object 
required: 
- success 
- blockHash 
- blockNumber 
- blockTimestamp 
- gasUsed 
- transactionHash 
properties: 
logs: 
type: array 
items: 
title: Log object 
type: object 
properties: 
address: 


$ref: ‘#/components/schemas/address 


data: 

title: data 

$ref: '#/components/schemas/bytes' 
topics: 


title: topics 
type: array 
items: 
$ref: '#/components/schemas/bytes32' 
success: 
type: boolean 
title: Whether the call succeeded 
blockHash: 
title: The hash of the block in which the call was included 
$ref: '#/components/schemas/bytes32' 
blockNumber : 
title: The number of the block in which the call was included 
$ref: '#/components/schemas/uint' 
blockTimestamp: 
title: The timestamp of the block in which the call was included 
$ref: '#/components/schemas/uint' 
gasUsed: 
title: How much gas the call actually used 
$ref: '#/components/schemas/uint' 
transactionHash: 
title: The hash of the transaction in which the call was made 
$ref: '#/components/schemas/bytes32' 
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wallet_getBundleStatus Example Parameters 


As with the return value of wallet_sendFunctionCallBundle , the bundle identifier may 
be any string of max length 66. 


It may be the hash of the call bundle: 
"@xe670eC64341771606e55d6b4ca35ala6b75ee3d5145a99d05921026d1527331" 


It may contain a numeric identifier as a hex string: 


"@xe1" 


It may be a base64 encoded string: 


"aGVsbG8gd29ybGQ=" 


wallet_getBundleStatus Example Return Value 


{ 
"calls": [ 
{ 
"status": "CONFIRMED", 
"receipt": { 
"logs": [ 
{ 
"address": "@xa922b54716264130634d6ff183747a8ead91a4@b", 
"topics": [ 
"@x5a2a90727cc9dee0dd860b1132a5c977c97O2bb3a52aFe360c9c22F0e9451a68" 
l 
"data": "@xabcd" 
} 
], 
"success": true, 
"blockHash": "@xf19bbafd9fd0124ec110b848e8de4ab4F62bF60c189524e54213285e7F524 
"blockNumber": "@xabcd", 
"plockTimestamp": "“@xabcdef", 
"gasUsed": "@xdef", 


"transactionHash": "@x9b7bb827c2e5e3c1a0a44dc53e573aaQb3af3bd1f9F5ed03071b1¢ 
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"status": "PENDING" 


wallet_showBundleStatus 


Requests that the wallet present UI showing the status of the given bundle. This 
allows dapps to delegate the display of the function call status to the wallet, which 
can most accurately render the current status of the bundle. This RPC is intended to 
replace the typical user experience of a dapp linking to a block explorer for a given 
transaction hash. 


e The wallet MAY ignore the request, for example if the wallet is busy with 
other user actions. 

e The wallet MAY direct the user to a third party block explorer for more 
information. 


wallet_showBundleStatus OpenRPC Specification 


- name: wallet_showBundleStatus 
summary: Requests that the wallet show the status of the bundle with the given ide 
params: 
- name: Bundle identifier 
required: true 
schema: 
type: string 
maxLength: 66 


result: 
name: Empty 
schema: 
type: "null" 


wallet_showBundleStatus Example Parameters 


[ 
"@xe670eCc64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" 


wallet_showBundleStatus Example Return Value 


null 


Rationale 
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Account abstracted wallets, either via EIP-3074 or EIP-4337 or other specifications, 
have more capabilities than regular EOA accounts. 


The eth_sendTransaction and eth_getTransactionReceipt methods limit the quality of 
in-dapp transaction construction and status tracking. It's possible for dapps to stop 
tracking transactions altogether and leave that UX to the wallet, but it is a better UX 
when dapps provide updates on transactions constructed within the dapp, because 
dapps will always have more context than the wallets on the action that a set of calls 
is meant to perform. For example, an approve and swap might both be related to a 
trade that a user is attempting to make. Without these APIs, it’s necessary for a dapp 
to represent those actions as individual transactions. 


Backwards Compatibility 


Wallets that do not support the following methods should return error responses to 
the new JSON-RPC methods. Dapps MAY attempt to send the same bundle of calls 
via eth_sendTransaction when they receive a not implemented call, or otherwise 
indicate to the user that their wallet is not supported. 


Security Considerations 


Dapp developers MUST treat each call in a bundle as if the call was an independent 
transaction. In other words, there may be additional untrusted transactions between 
any of the calls in a bundle. The calls in the bundle may also be included in separate, 
non-contiguous blocks. There is no constraint over how long it will take a bundle to 
be included. Dapps must encode deadlines in the smart contract calls as they do 
today. Dapp developers MUST NOT assume that all calls are sent in a single 
transaction. 
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